chore: migrate from Ladle to Storybook #930

jeffredodd · 2026-01-08T21:08:46Z

Summary

This PR migrates the SDK's component development environment from Ladle to Storybook 8.6.15.

Goal

Port existing Ladle functionality to Storybook — this is NOT an effort to implement new Storybook features. The goal is a 1:1 migration that maintains our existing development workflow while moving to a more widely-adopted tool with better long-term support.

Testing

Used cursor + playwright MCP to get us to 100% matching between chromeless screenshots of stories

What Changed

Added

.storybook/ configuration directory:
- main.ts — Story discovery patterns, addons, Vite config
- preview.tsx — Global decorators with providers, component adapter toolbar toggle
- helpers/FormWrapper.tsx — Form wrapper with Storybook actions integration
- helpers/useStoryState.tsx — State management helper for interactive stories
- helpers/MockBaseProvider.tsx — Mock provider for stories needing BaseContext
- adapters/PlainComponentAdapter.tsx — Plain HTML component adapter (migrated from Ladle)
- static/demo-images/ — Static assets for stories
Storybook dependencies (@storybook/* 8.6.15, storybook-dark-mode)
npm scripts: storybook, build-storybook
.gitignore entries for storybook-static/ and *storybook.log

Modified

69 story files — Converted from Ladle's Story<T> format to Storybook CSF3 (Meta/StoryObj)
tsconfig.json — Updated paths from .ladle to .storybook
vite.config.ts — Updated exclusion patterns for .storybook
eslint.config.mjs — Added .storybook/**/* to ignores
CONTRIBUTING.md — Updated developer instructions to use npm run storybook
package.json — Added Storybook deps, removed @ladle/react

Removed

.ladle/ directory and all Ladle configuration
@ladle/react dependency
ladle npm script

What Did NOT Change

No production code changes — All changes are in story files, config, and dev dependencies
No component logic changes — Stories render the same components as before
No test changes — Unit tests remain untouched (all 1018 tests pass)
No build output changes — SDK build produces identical output

Verification

Check	Status
TypeScript (`npm run tsc`)	✅ Pass
ESLint (`npm run lint:check`)	✅ Pass
Prettier (`npm run format:check`)	✅ Pass
Unit tests (`npm run test -- --run`)	✅ Pass (1018 tests)
SDK build (`npm run build`)	✅ Pass
Storybook build (`npm run build-storybook`)	✅ Pass
Storybook smoke test	✅ Pass

⚠️ Review Notes

This migration was largely AI-assisted. While all automated checks pass and manual spot-checks have been performed, reviewers should:

Spot-check story files — Verify a sampling of stories render correctly in Storybook
Test the component adapter toggle — Toolbar should switch between React Aria and Plain HTML
Verify interactive stories — Form fields, state changes, etc. work as expected

The risk is mitigated by:

No production code was modified
All existing tests continue to pass
Story files are development-only and don't affect the published SDK

How to Test

npm install
npm run storybook
# Visit http://localhost:6006

socket-security · 2026-01-08T21:09:24Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

[email protected]
[email protected]

View full report

jeffredodd · 2026-01-08T21:15:33Z

@SocketSecurity ignore npm/[email protected]

jeffredodd · 2026-01-08T21:17:04Z

@SocketSecurity ignore npm/[email protected]

- Replace @ladle/react with Storybook 8.6.15 - Convert all 69 story files from Ladle's Story<T> format to Storybook CSF3 - Add .storybook/ configuration with providers, component adapter toolbar - Migrate helpers: FormWrapper, PlainComponentAdapter, add useStoryState - Update tsconfig.json, vite.config.ts, eslint.config.mjs for .storybook paths - Update CONTRIBUTING.md with Storybook instructions - Add storybook-static/ and *storybook.log to .gitignore

Copilot

Pull request overview

This PR successfully migrates the SDK's component development environment from Ladle to Storybook 8.6.15, maintaining a 1:1 functional parity while adopting a more widely-supported tooling ecosystem. The migration includes configuration setup, helper utilities, and conversion of 69 story files from Ladle's format to Storybook's CSF3 format.

Key changes:

Replaced Ladle with Storybook 8.6.15 and configured addons (essentials, interactions, a11y, dark mode)
Migrated all story files from action() to fn().mockName() pattern
Converted useLadleState to useStoryState for state management in stories
Updated component adapter toggle from floating button to Storybook toolbar

Reviewed changes

Copilot reviewed 73 out of 78 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`.storybook/main.ts`	Storybook configuration with Vite integration and addon setup
`.storybook/preview.tsx`	Global decorators with providers and component adapter toolbar
`.storybook/helpers/*`	Migrated helper utilities (FormWrapper, useStoryState, MockBaseProvider)
`.storybook/adapters/PlainComponentAdapter.tsx`	Migrated plain HTML component adapter
`package.json`	Added Storybook dependencies, removed Ladle
`vite.config.ts`	Updated exclusion patterns from `.ladle` to `.storybook`
`tsconfig.json`	Updated path aliases from `~ladle/` to `~storybook/`
`eslint.config.mjs`	Added `.storybook/*/` to ignores
69 story files	Converted from Ladle format to Storybook CSF3 format
`.ladle/*`	Removed all Ladle configuration and helpers
`CONTRIBUTING.md`	Updated developer instructions to use Storybook
`.gitignore`	Added Storybook build output entries

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/components/Payroll/PayrollList/PayrollList.stories.tsx

src/components/Common/DocumentViewer/DocumentViewer.stories.tsx

serikjensen

Looking good thanks for taking this on! left a few comments

serikjensen · 2026-01-09T22:32:52Z

.storybook/main.ts

+      css: {
+        preprocessorOptions: {
+          scss: {
+            api: 'modern-compiler',
+            additionalData: `@use "@/styles/Helpers" as *; @use '@/styles/Responsive' as *;\n`,
+          },
+        },
+      },


Could we import our codebase CSS config here so that changes to our codebase config don't result in breaking storybook?

serikjensen · 2026-01-09T22:34:28Z

.storybook/preview.tsx

+    <I18nextProvider i18n={SDKI18next}>
+      <LocaleProvider locale="en-US" currency="USD">
+        <ThemeProvider>


These providers are already set in GustoProviderCustomUIAdapter. looks like you can just set the props on that and remove these?

serikjensen · 2026-01-09T22:58:14Z

src/components/Common/UI/Badge/Badge.stories.tsx

 }

-export default {
+const meta: Meta<typeof BadgeWrapper> = {


Nit: any reason this is getting changed to meta and then using the default export? Vs. the other default exports? just wondering since if there's a needed change here i'm not seeing it on the other exports

Good catch, i'll look into that one

jeffredodd force-pushed the jdj/storybook branch from f9719b1 to 13bc3b5 Compare January 8, 2026 21:17

jeffredodd force-pushed the jdj/storybook branch from 13bc3b5 to 121d889 Compare January 8, 2026 21:21

jeffredodd requested review from dmortal and serikjensen January 8, 2026 21:23

jeffredodd marked this pull request as ready for review January 8, 2026 21:23

Copilot AI review requested due to automatic review settings January 8, 2026 21:23

Copilot started reviewing on behalf of jeffredodd January 8, 2026 21:24 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

src/components/Payroll/PayrollList/PayrollList.stories.tsx Show resolved Hide resolved

src/components/Common/DocumentViewer/DocumentViewer.stories.tsx Show resolved Hide resolved

serikjensen reviewed Jan 9, 2026

View reviewed changes

refactor: address PR feedback - share CSS config and simplify providers

8e73e4d

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: migrate from Ladle to Storybook #930

chore: migrate from Ladle to Storybook #930

Uh oh!

jeffredodd commented Jan 8, 2026 •

edited

Loading

Uh oh!

socket-security bot commented Jan 8, 2026 •

edited

Loading

Uh oh!

jeffredodd commented Jan 8, 2026

Uh oh!

jeffredodd commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

serikjensen left a comment

Uh oh!

serikjensen Jan 9, 2026

Uh oh!

serikjensen Jan 9, 2026

Uh oh!

serikjensen Jan 9, 2026

Uh oh!

jeffredodd Jan 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chore: migrate from Ladle to Storybook #930

Are you sure you want to change the base?

chore: migrate from Ladle to Storybook #930

Uh oh!

Conversation

jeffredodd commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Goal

Testing

What Changed

Added

Modified

Removed

What Did NOT Change

Verification

⚠️ Review Notes

How to Test

Uh oh!

socket-security bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jeffredodd commented Jan 8, 2026

Uh oh!

jeffredodd commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

serikjensen left a comment

Choose a reason for hiding this comment

Uh oh!

serikjensen Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

serikjensen Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

serikjensen Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

jeffredodd Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jeffredodd commented Jan 8, 2026 •

edited

Loading

socket-security bot commented Jan 8, 2026 •

edited

Loading